---
title: Open Document from URL
description: Learn how to use the openDocumentUrl method in @embedpdf/engines to open a PDF from a URL.
searchable: true
---

# openDocumentUrl

import { Callout } from '@/components/callout'

Opens a PDF document from a given URL by downloading the entire file.

## Signature

```typescript
openDocumentUrl(file: PdfFileUrl, options?: PdfOpenDocumentUrlOptions): PdfTask<PdfDocumentObject>;
```

## Description

This function initiates the process of loading a PDF file from a remote URL. It fetches the complete file content into memory before opening it.

<Callout>
**Note on Loading Strategy**
Currently, this function **always** downloads the entire PDF file. Support for progressive loading via HTTP range requests is planned for a future release. The `mode` option is reserved for this future enhancement and will have no effect on the current behavior.
</Callout>

## Parameters

| Name | Type | Description |
| :--- | :--- | :--- |
| **`file`** | `PdfFileUrl` | An object containing a unique `id` you provide and the `url` of the PDF file. Example: `{ id: 'unique-doc-id', url: 'https://example.com/document.pdf' }` |
| **`options`** | `PdfOpenDocumentUrlOptions` | (Optional) An object to configure loading. Can include a `password` for encrypted files. |

### `PdfOpenDocumentUrlOptions`

```typescript
export interface PdfOpenDocumentUrlOptions {
  password?: string;
  /**
   * NOTE: This option is reserved for future use. Currently, only the 'full-fetch'
   * behavior is implemented regardless of the selected mode.
   */
  mode?: 'auto' | 'range-request' | 'full-fetch';
}
```

## Returns

`PdfTask<PdfDocumentObject>`

A `Task` that resolves with a `PdfDocumentObject` when the document is successfully opened. The `PdfDocumentObject` contains metadata about the PDF, such as the page count and the dimensions of each page.

If the operation fails (e.g., the URL is invalid, the file is corrupted, or the password is incorrect), the `Task` will be rejected with a `PdfErrorReason`.

See [Concepts: Tasks](../tasks.md) for more on how to handle asynchronous operations.

## Example

```typescript
// Assuming 'engine' is an initialized PdfiumEngine instance

const fileUrl = { id: 'my-doc', url: '/path/to/document.pdf' };

try {
  // Use .toPromise() to work with async/await
  const document = await engine.openDocumentUrl(fileUrl, { password: 'my-secret-password' }).toPromise();

  console.log(`Successfully opened document with ${document.pageCount} pages.`);

  // Now you can use the 'document' object with other engine methods
  // e.g., engine.renderPage(document, document.pages[0]);

} catch (error) {
  console.error('Failed to open document:', error);
}
```

## See Also

  - [Open Document from Buffer](open-document-buffer.md)
  - [Close Document](close-document.md)